home *** CD-ROM | disk | FTP | other *** search
/ The Utilities Experience / The Utilities Experience - Volume 1.iso / software / misc / e-n / hsc / src_docs / features / macros.hsc < prev    next >
Text File  |  1995-10-07  |  4KB  |  125 lines
  1. <$INCLUDE FILE="inc/macro.hsc">
  2. <WEBPAGE chapter="hsc - Features - " title="Macros">
  3.  
  4. Okay, here are some examples of macro definitions:
  5.  
  6. <$MACRO EXMAC>
  7. <BLOCKQUOTE><TT><$MACRO
  8. </$MACRO>
  9. <$MACRO /EXMAC>
  10. </$MACRO></TT></BLOCKQUOTE>
  11. </$MACRO>
  12.  
  13. <H2>Use as a shortcut</H2>
  14.  
  15. You can define a macro called <TT>MY_ADDRESS</TT> that only is a
  16. shortcut for your email-address like
  17. <EXMAC>MY_ADDRESS>hugo@some.where</EXMAC>
  18. So every time, you insert the macro-tag
  19. <BLOCKQUOTE>
  20. <TG>MY_ADDRESS</TG>
  21. </BLOCKQUOTE>
  22. in your HSC-source, it will be replaced with the email address
  23. seen above in the HTML-file.
  24.  
  25. <H2>Create your own logical style</H2>
  26.  
  27. One of the most embarassing facts within HTML are physical/logical
  28. styles. Taking a look at the HTML 3.0 proposed things, you find
  29. loads of new styles: <TG>AU</TG> for authors, <TG>SAMP</TG> for
  30.     sequences of litteral characters
  31. and so on... No one knows where this will end, and I'm just waiting
  32. for physical styles like
  33. <TG>TIM_BERNERS_LEE_S_LOGICAL_STYLE_TO_RENDER_NAMES_OF_HIS_FRIENDS</TG>.<P>
  34.  
  35. Anyway, while other people think about which logical style should get his
  36. own tag and which not, you can define your own styles. For example, a
  37. logical style to render a filename could look like this:
  38.  
  39. <EXMAC>FNM> <I> </EXMAC>
  40. <EXMAC>/FNM> </I> </EXMAC>
  41.  
  42. Your new style can be used like all other styles:
  43. <BLOCKQUOTE><TT>
  44. ..open the file <TG>FNM</TG>hugo.txt<TG>/FNM</TG> and..
  45. </TT></BLOCKQUOTE>
  46.  
  47. In this case, filenames will be rendered <I>italic</I>. This seems much
  48. more reasonable to me then producing heaps of logical styles, but..<P>
  49.  
  50. Note that you just created a container that requires an openig and
  51. closing tag.
  52.  
  53. <H2>Macros with custom attributes</H2>
  54.  
  55. Now the most subtile part starts: you can add attributes to macros.
  56. Attributes are compareable to function arguments in programming languages
  57. like Pascal, Oberon or E.<P>
  58.  
  59. An attribute is defined with
  60. <BLOCKQUOTE>
  61. <I>name</I> ":" <I>type</I> [ "=" <I>default value</I> ]
  62. </BLOCKQUOTE>
  63.  
  64. Legal attribute types are:
  65. <UL>
  66. <LI>STRING: any text
  67. <LI>URI: references to an URI. Is affected bye command line options like
  68.     <A HREF="options.html">AbsUri</A> or <A HREF="options.html">CheckUri</A>.
  69. <LI>BOOL: boolean flag
  70. <LI>ENUM: enumerator type; accepts only given values (eg the <TT>ALIGN</TT>
  71.     attribute of <TG>IMG</TG>).
  72. </UL>
  73.  
  74. So here's an example to understand that rather theoretical excess you just read
  75. and didn't understand at all:
  76.  
  77. <EXMAC>BUTTON_NEXT NXTREF:uri><BR>
  78. <A HREF=<NXTREF>><BR>
  79. <IMG SRC="image/next.gif" ALT="Next"><BR>
  80. </A><BR>
  81. </EXMAC>
  82.  
  83. This defines a macro that defines a button that references to the next page.
  84. As every page has its own next page, you can set one attribute for this macro:
  85. <TT>NXTREF</TT>, which is the URI that should be referenced as the "next"
  86. page.<P>
  87.  
  88. So an example usage of this macro would be:
  89. <BLOCKQUOTE><TT>
  90. <TG>BUTTON_NEXT NXTREF="sepp.html"</TG>
  91. </TT></BLOCKQUOTE>
  92.  
  93. Note that the value of <TT>NXTREF</TT> is passed to the <TT>HREF</TT> attribute
  94. within the <TG>A</TG> tag when the macro is extracted.<P>
  95.  
  96. If an attribute should get its value from an other attribute, the source
  97. attributes name needs to be enclosed in "<TT><..></TT>", like
  98. <TT>HREF=<NXTREF></TT> (see above), which assigns the value of the macro
  99. attribute <TT>NXTREF</TT> to the tag attribute <TT>HREF</TT>.<P>
  100.  
  101. <H2>Some Notes</H2>
  102.  
  103. Names for macros and attributes are case-insensitive.<P>
  104.  
  105. Macro attributes can only be defined within opening macros. The
  106. coresponding closing macro automatically inherits all attributes of
  107. its opening macro. This seems more HTML-like to me.<P>
  108.  
  109. This is not all that can be told about <hsc>'s macros. Macros also
  110. support default values and several flags. Yeah, I really should
  111. improve the docs..
  112.  
  113. If you want
  114. to take a look at some quite complex macros, take a look at the file
  115. <FILE>
  116. <* Note: this creates a link with absolute uri not converted *>
  117. <|<A HREF="../../src_docs/inc/macro.hsc">src_docs/inc/macro.hsc</A>|>
  118. </FILE> in this distribution.<P>
  119.  
  120. <MAIN>
  121. <PREV href="features/absuris.html">
  122. <NEXT href="features/rplcent.html">
  123. </WEBPAGE>
  124.  
  125.